Skip to content

Conversation

@alexdewar
Copy link
Collaborator

Description

I've copied over the section about dispatch for flexible assets from Adam's LaTeX document. I converted it using pandoc, then had to do some fiddling to get the equations to format properly (sadly, this is a bit of an issue with mdbook).

While I was at it, I renumbered the sections and removed references to sections which don't exist in our docs (just in the LaTeX version).

I've only skimmed the content, but I figure we can revisit it when we actually start implementing #360. The content might need to change as we go, but I thought it was a good idea to have this as a starting point for now.

Closes #1104.

Type of change

  • Bug fix (non-breaking change to fix an issue)
  • New feature (non-breaking change to add functionality)
  • Refactoring (non-breaking, non-functional change to improve maintainability)
  • Optimization (non-breaking change to speed up the code)
  • Breaking change (whatever its nature)
  • Documentation (improve or add documentation)

Key checklist

  • All tests pass: $ cargo test
  • The documentation builds and looks OK: $ cargo doc
  • Update release notes for the latest release if this PR adds a new feature or fixes a bug
    present in the previous release

Further checks

  • Code is commented, particularly in hard-to-understand areas
  • Tests added that prove fix is effective or that feature works

Copilot AI review requested due to automatic review settings February 2, 2026 11:49
@codecov
Copy link

codecov bot commented Feb 2, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.55%. Comparing base (bb99332) to head (d99e674).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1111   +/-   ##
=======================================
  Coverage   87.55%   87.55%           
=======================================
  Files          55       55           
  Lines        7580     7580           
  Branches     7580     7580           
=======================================
  Hits         6637     6637           
  Misses        640      640           
  Partials      303      303           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds comprehensive documentation for flexible assets to the dispatch optimization model, ported from a LaTeX document. The flexible assets feature allows assets to adjust their input/output mix within defined constraints, controlled by an overall efficiency parameter. The PR also renumbers existing sections and updates internal cross-references.

Changes:

  • Added new Section B covering flexible assets, including asset-specific sets, parameters, decision variables, objective contributions, and operational constraints
  • Renumbered "Full Model Construction" from Section B to Section C
  • Updated code reference URL to match new section numbering
  • Modified objective function and constraint descriptions to reflect the simplified model structure (removing unimplemented features like scope policies and trade)

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File Description
docs/model/dispatch_optimisation.md Added comprehensive flexible assets documentation (Section B) and renumbered subsequent sections; updated objective function and constraints to reference flexible assets
src/simulation/optimisation/constraints.rs Updated documentation URL reference to point to renumbered commodity balance section

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines 183 to 344
- Capacity & Availability constraints for all assets \\( a \in \mathbf{A} \\)
(as per A.4 and E.5).

- Scope policy constraints (B.5).

- Region-to-Region Trade Limits (C.5.A).
(as per [A.4] and [B.5])

- Pool-Based Trade Limits (D.5.A).
- [Flexible Asset operational constraints][B.5]
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The constraint list has some redundancy. The first bullet mentions B.5 for capacity constraints, and the second bullet also references B.5 for flexible asset operational constraints. Since B.5 includes both capacity/availability constraints AND the other operational constraints for flexible assets, the second bullet is redundant. Consider either: (1) removing the second bullet entirely, or (2) clarifying that the first bullet only refers to capacity/availability (not all B.5 constraints), while the second bullet refers to the other operational constraints in B.5 (efficiency, input/output share constraints, etc.).

Copilot uses AI. Check for mistakes.
Comment on lines 324 to 331

\\[
\begin{aligned}
\text{Minimise: } &(\text{Core Asset Operational Costs from A.3 and E.4}) \\\\
&+ (\text{Scope Policy Costs/Credits from B.4}) \\\\
&+ (\text{Region-to-Region Trade Costs from C.4}) + (\text{Pool-Based Trade Costs from D.4}) \\\\
\text{Minimise: } &(\text{Core Asset Operational Costs from A.3 and B.4}) \\\\
&+ \sum_{c \in \mathbf{C}^{VoLL},r,t} UnmetD[c,r,t] \cdot VoLL[c,r]
\quad \text{(Penalty for Unserved Demand)}
\end{aligned}
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a discrepancy between the descriptive text and the actual objective function equation. The text (lines 320-323) states that the objective includes "financial impacts from policy scopes (taxes minus credits), costs of inter-regional trade, costs of pool-based trade", but the equation (lines 327-328) only includes "Core Asset Operational Costs from A.3 and B.4" and the penalty for unserved demand. Either the descriptive text should be updated to match the equation (removing mentions of scope policies, R2R trade, and pool trade), or the equation should include these terms.

Copilot uses AI. Check for mistakes.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, the equation is currently incomplete. We haven't added these features yet.

Copilot AI review requested due to automatic review settings February 11, 2026 13:52
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings February 11, 2026 14:11
@alexdewar alexdewar force-pushed the flexible-assets-docs branch from 945ee6e to d99e674 Compare February 11, 2026 14:14
@alexdewar alexdewar requested a review from Aurashk February 11, 2026 14:14
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 8 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +241 to +250
\\[
\begin{aligned}
&act[a,r,t] \cdot cost\_{var}[a,r,t] \\\\
&+ \sum\_{c \in \mathbf{C}^{eff\\_ in}\_a} InputSpec[a,c,r,t] \cdot cost\_{input}[a,c] \\\\
&+ \sum\_{c \in \mathbf{C}^{eff\\_ out}\_a} OutputSpec[a,c,r,t] \cdot cost\_{output}[a,c] \\\\
&+ \sum\_{c \in \mathbf{C}^{aux\\_ in}\_a} (act[a,r,t] \cdot coeff\_{aux\\_ in}[a,c])
\cdot cost\_{input}[a,c] \\\\
&+ \sum\_{c \in \mathbf{C}^{aux\\_ out}\_a} (act[a,r,t] \cdot coeff\_{aux\\_ out}[a,c])
\cdot cost\_{output}[a,c] \\\\
\end{aligned}
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The flexible-asset objective contribution is presented without the outer summations over assets/regions/time. As written, it reads like a single (a,r,t) term rather than the contribution to the total objective (contrast with A.3 which includes \sum_{a}\sum_{r,t}). Either add the missing summations or explicitly state that this is the per-(a,r,t) term that is summed in the full objective.

Copilot uses AI. Check for mistakes.
Comment on lines 395 to +397
OutputSpec[a,c,r,t] & \text{if } c \in \mathbf{C}^{eff\\_out}\_a \\\\
act[a,r,t] \cdot coeff\_{aux\\_out}[a,c] & \text{if } c \in \mathbf{C}^{aux\_out}\_a \\ 0
& \text{otherwise}
act[a,r,t] \cdot coeff\_{aux\\_out}[a,c] & \text{if } c \in \mathbf{C}^{aux\\_out}\_a \\\\
0 & \text{otherwise}
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the flex-asset production case distinction, the set names use \mathbf{C}^{eff\_out}\_a / \mathbf{C}^{aux\_out}\_a. In LaTeX, \_ renders a literal underscore, so the intended subscript _a won’t render correctly. Use _a (unescaped) for subscripts (consistent with earlier set definitions like \mathbf{C}^{eff\_ out}_a).

Copilot uses AI. Check for mistakes.
Comment on lines +244 to +249
&+ \sum\_{c \in \mathbf{C}^{eff\\_ in}\_a} InputSpec[a,c,r,t] \cdot cost\_{input}[a,c] \\\\
&+ \sum\_{c \in \mathbf{C}^{eff\\_ out}\_a} OutputSpec[a,c,r,t] \cdot cost\_{output}[a,c] \\\\
&+ \sum\_{c \in \mathbf{C}^{aux\\_ in}\_a} (act[a,r,t] \cdot coeff\_{aux\\_ in}[a,c])
\cdot cost\_{input}[a,c] \\\\
&+ \sum\_{c \in \mathbf{C}^{aux\\_ out}\_a} (act[a,r,t] \cdot coeff\_{aux\\_ out}[a,c])
\cdot cost\_{output}[a,c] \\\\
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the B.4 objective expression, the summation index sets are written with \mathbf{C}^{...}\_a (e.g., \mathbf{C}^{eff\_ in}\_a, \mathbf{C}^{aux\_ out}\_a). In LaTeX, \_ renders a literal underscore, so these won’t typeset as the intended subscript _a. Use _a (unescaped) for subscripts, consistent with the set definitions earlier (\mathbf{C}^{eff\_ in}_a, etc.).

Copilot uses AI. Check for mistakes.
Comment on lines +187 to +189
- \\( \eta[a] \\): The overall process efficiency (\\( \in (0,1] \\)) of flexible asset \\( a \\),
relating total common units of outputs in \\( \mathbf{C}^{eff\\_out}_a \\) to inputs in \\(
\mathbf{C}^{eff\\_in}_a \\).
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Math formatting is still inconsistent for names like eff\_in/eff\_out: earlier you use the spaced form noted at the top of the file (e.g., \mathbf{C}^{eff\_ in}_a, \mathbf{C}^{eff\_ out}_a), but here it switches to \mathbf{C}^{eff\_out}_a / \mathbf{C}^{eff\_in}_a. Given the mdbook rendering note, it’s safer to standardize on one form throughout (preferably the spaced version used elsewhere in this document).

Copilot uses AI. Check for mistakes.
Comment on lines +277 to +280
\\[
\sum\_{c \in \mathbf{C}^{eff\\_out}\_a} OutputSpec[a,c,r,t] \cdot factor\_{CU}[c]
= ActualTotalEffOutputCU[a,r,t]
\\]
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The efficiency-constrained output definition equation uses \mathbf{C}^{eff\_out}\_a in the summation index. \_ renders a literal underscore, so the intended subscript ..._a will not render correctly. Use _a (unescaped) for subscripts.

Copilot uses AI. Check for mistakes.
Comment on lines 341 to +344
- Capacity & Availability constraints for all assets \\( a \in \mathbf{A} \\)
(as per A.4 and E.5).

- Scope policy constraints (B.5).
(as per [A.4] and [B.5])

- Region-to-Region Trade Limits (C.5.A).
- [Flexible Asset operational constraints][B.5]
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The constraints list is currently redundant: the first bullet already references B.5, and the next bullet links to B.5 again. Consider making the first bullet reference only A.4 for capacity/availability, and keep a separate bullet for the remaining flexible-asset operational constraints (B.5), or otherwise remove the duplication.

Copilot uses AI. Check for mistakes.
Comment on lines +227 to +233
- \\( InputSpec[a,c,r,t]\ge0 \quad \forall c \in \mathbf{C}^{eff\\_ in}\_a \\): Actual amount of
efficiency-constrained input commodity \\( c \\) consumed by asset \\( a \\) in region \\( r \\),
time \\( t \\) (in its native physical units).

- \\( OutputSpec[a,c,r,t]\ge0 \quad \forall c \in \mathbf{C}^{eff\\_ out}\_a \\): Actual amount of
efficiency-constrained output commodity \\( c \\) produced by asset \\( a \\) in region \\( r \\),
time \\( t \\) (in its native physical units).
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the decision-variable definitions, the set qualifiers use \_a (e.g., \mathbf{C}^{eff\_ in}\_a / \mathbf{C}^{eff\_ out}\_a). In LaTeX \_ renders a literal underscore, so this will not typeset the intended subscript ..._a. Use _a (unescaped) consistently, matching the set definitions earlier in the section.

Copilot uses AI. Check for mistakes.
Comment on lines +268 to +271
\\[
\sum\_{c \in \mathbf{C}^{eff\\_ in}\_a} InputSpec[a,c,r,t] \cdot factor\_{CU}[c]
= ActualTotalEffInputCU[a,r,t]
\\]
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The efficiency-constrained input definition equation uses \mathbf{C}^{eff\_ in}\_a in the summation index. \_ produces a literal underscore in LaTeX, so the subscript will be rendered incorrectly. Use _a (unescaped) for subscripts.

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add docs for flexible assets from LaTeX document

1 participant